.TH SHUTTLEXPRESS "1" "2011-01-13" "LinuxCNC Documentation" "HAL User's Manual"
.de TQ
.br
.ns
.TP \\$1
..
.SH NAME
shuttlexpress \- control HAL pins with the ShuttleXpress device made by Contour Design
.SH SYNOPSIS
\fIloadusr\fR \fBshuttlexpress\fR \fI[DEVICE ...]\fR
.SH DESCRIPTION
shuttlexpress is a userspace HAL component that interfaces Contour
Design's ShuttleXpress device with LinuxCNC's HAL.  The ShuttleXpress has
five momentary buttons, a 10 counts/revolution jog wheel with detents,
and a 15-position spring-loaded outer wheel that returns to center
when released.
.PP
If it is started without command-line arguments, it will probe all
/dev/hidraw* device files for ShuttleXpress devices, and use all devices
found.  If it is started with command-line arguments, only will only
probe the devices specified.
.SH UDEV
The shuttlexpress module needs read permission on the /dev/hidraw*
device files.  This can be accomplished by adding a file
\fB/etc/udev/rules.d/99-shuttlexpress.rules\fR, with the following contents:

SUBSYSTEM=="hidraw", ATTRS{idVendor}=="0b33", ATTRS{idProduct}=="0020", MODE="0444"

.SH A warning about the Jog Wheel
The ShuttleXpress device has an internal 8-bit counter for the current
jog-wheel position.  The shuttlexpress driver can not know this value
until the ShuttleXpress device sends its first event.  When the first
event comes into the driver, the driver uses the device's reported
jog-wheel position to initialize counts to 0.

This means that if the first event is generated by a jog-wheel move,
that first move will be lost.

Any user interaction with the ShuttleXpress device will generate an event,
informing the driver of the jog-wheel position.  So if you (for example)
push one of the buttons at startup, the jog-wheel will work fine and
notice the first click.

.SH Pins
.TP
(bit out) \fIshuttlexpress.0.button-0\fR
.TP
(bit out) \fIshuttlexpress.0.button-0-not\fR
.TP
(bit out) \fIshuttlexpress.0.button-1\fR
.TP
(bit out) \fIshuttlexpress.0.button-1-not\fR
.TP
(bit out) \fIshuttlexpress.0.button-2\fR
.TP
(bit out) \fIshuttlexpress.0.button-2-not\fR
.TP
(bit out) \fIshuttlexpress.0.button-3\fR
.TP
(bit out) \fIshuttlexpress.0.button-3-not\fR
.TP
(bit out) \fIshuttlexpress.0.button-4\fR
.TP
(bit out) \fIshuttlexpress.0.button-4-not\fR

    The five buttons around the outside, starting with the
    counter-clockwise-most one.

.TP
(s32 out) \fIshuttlexpress.0.counts\fR

    Accumulated counts from the jog wheel (the inner wheel).

.TP
(s32 out) \fIshuttlexpress.0.spring-wheel-s32\fR

    The current deflection of the spring-wheel (the outer wheel).
    It's 0 at rest, and ranges from -7 at the counter-clockwise
    extreme to +7 at the clockwise extreme.

.TP
(float out) \fIshuttlexpress.0.spring-wheel-f\fR

    The current deflection of the spring-wheel (the outer wheel).
    It's 0 at rest, -1 at the counter-clockwise extreme, and
    +1 at the clockwise extreme.  (The ShuttleXpress device reports the
    spring-wheel position quantized from -7 to +7, so this pin reports
    only 15 discrete values in its range.)

